@opentelemetry/semantic-conventions

What is @opentelemetry/semantic-conventions?

The @opentelemetry/semantic-conventions package provides standardized naming and semantic conventions for attributes in OpenTelemetry. These conventions help ensure that telemetry data is consistent, interpretable, and analyzable across different systems and services. The package includes constants for resource attributes, span attributes, and event names that are recommended by the OpenTelemetry specification.

What are @opentelemetry/semantic-conventions's main functionalities?

Resource Attributes

Defines standard attributes to be used for service resources, allowing you to annotate your telemetry data with information about the service instance.

{"service.name": 'my-service', "service.version": '1.0.0', "service.instance.id": 'instance-123'}

Span Attributes

Provides a set of standard attributes for spans, which represent individual operations within a trace. These attributes can be used to add metadata about the operation, such as HTTP method, URL, and status code.

{"http.method": 'GET', "http.url": 'https://example.com', "http.status_code": 200}

Event Names

Includes standardized event names for logging exceptions, messages, and metrics within spans. This helps in categorizing and querying telemetry events.

"exception", "message", "metric"

Other packages similar to @opentelemetry/semantic-conventions

elastic-apm-node

Elastic APM Node.js Agent is a real user monitoring library that provides similar functionality to OpenTelemetry. It allows you to instrument your Node.js applications to track performance metrics and errors. While it also adheres to certain conventions, it is tailored to work with the Elastic Stack, and may not be as flexible as OpenTelemetry in terms of vendor neutrality.

jaeger-client

Jaeger client libraries provide features for distributed tracing similar to OpenTelemetry. They offer their own set of conventions for tracing data. While Jaeger is compatible with OpenTelemetry through exporters, its native conventions are not the same as those defined by OpenTelemetry's semantic conventions.

README

OpenTelemetry Semantic Conventions

Semantic Convention constants for use with the OpenTelemetry SDK/APIs. This document defines standard attributes for traces.

Installation

npm install --save @opentelemetry/semantic-conventions

Import Structure

This package has 2 separate exports. The main export (@opentelemetry/semantic-conventions) includes only stable semantic conventions. It is subject to the restrictions of semantic versioning 2.0. The /incubating export (@opentelemetry/semantic-conventions/incubating) contains all stable and unstable semantic conventions. It is NOT subject to the restrictions of semantic versioning and MAY contain breaking changes in minor releases.

Usage

Stable SemConv

import { 
  ATTR_NETWORK_PEER_ADDRESS,
  ATTR_NETWORK_PEER_PORT,
  ATTR_NETWORK_PROTOCOL_NAME,
  ATTR_NETWORK_PROTOCOL_VERSION,
  NETWORK_TRANSPORT_VALUE_TCP,
} from '@opentelemetry/semantic-conventions';

const span = tracer.startSpan(spanName, spanOptions)
  .setAttributes({
    [ATTR_NETWORK_PEER_ADDRESS]: 'localhost',
    [ATTR_NETWORK_PEER_PORT]: 8080,
    [ATTR_NETWORK_PROTOCOL_NAME]: 'http',
    [ATTR_NETWORK_PROTOCOL_VERSION]: '1.1',
    [ATTR_NETWORK_TRANSPORT]: NETWORK_TRANSPORT_VALUE_TCP,
  });

Unstable SemConv

import { 
  ATTR_PROCESS_COMMAND,
  ATTR_PROCESS_COMMAND_ARGS,
  ATTR_PROCESS_COMMAND_LINE,
} from '@opentelemetry/semantic-conventions/incubating';

const span = tracer.startSpan(spanName, spanOptions)
  .setAttributes({
    [ATTR_PROCESS_COMMAND]: 'cat',
    [ATTR_PROCESS_COMMAND_ARGS]: ['file1', 'file2'],
    [ATTR_CONTAINER_COMMAND_LINE]: 'cat file1 file2',
  });

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

1.27.0

:rocket: (Enhancement)

• feat: add processors for adding session.id attribute to spans and logs #4972

:bug: (Bug Fix)

• fix(sdk-trace-base): avoid keeping non-string status.message on Span#setStatus() #4999 @pichlermarc
• fix(sdk-metrics): Add missing catch and handle error in promise of PeriodicExportingMetricReader #5006 @jj22ee
• fix(opentelemetry-core): confusing log extract of composite propagator #5017 @rv2673
• fix(propagator-aws-xray-*): move propagators back to contrib repository #4966 @pichlermarc
  • The specification prohibits hosting these packages in the core repository
  • @opentelemetry/propagator-aws-xray is now located in open-telemetry/opentelemetry-js-contrib
  • @opentelemetry/propagator-aws-xray-lambda is now located in open-telemetry/opentelemetry-js-contrib

:house: (Internal)

• deps: set @opentelemetry/api dependency min version to 1.3.0 in examples, experimental/packages, integration-tests and selenium-tests #4992
• refactor(sdk-metrics): replace MetricsAttributes with Attributes #5021 @david-luna
• refactor(instrumentation-http): replace SpanAttributes and MetricsAttributes with Attributes #5023 @david-luna
• chore(exporter-zipkin): remove usages of Span constructor #5030 @david-luna
• test(instrumentation-http): remove usages of new Span in tests #5035 @david-luna